Skip to main content

Copy file or directory (file.copy)

Declaration​

ok, err = file.copy(src, dst [, mode])

Parameters​

  • src
    String. Absolute path of the source file or directory.
  • dst
    String. Complete absolute path of the resulting file or directory, including the destination file or directory name.
  • mode 20250914+
    String, optional. Copy mode. Values:
    • Empty string or omitted: default mode (no-clobber); fail if the destination already exists.
    • "overwrite" or "o": overwrite mode; replace the existing destination (the existing destination will be deleted).
    • "merge" or "m": merge mode (directories only); keep files already in the destination.
    • "overwrite-merge" or "om"/"mo": overwrite-merge mode; merge directories and overwrite files with the same name.

Returns​

  • ok
    Boolean. true on success, false on failure.
  • err
    String. Error message when the operation fails.

Description​

Copy the file or directory at src as dst.
This function means “copy as”, not “copy into”. dst specifies the final file or directory; the source file or directory name is not appended automatically. Even if the destination is an existing directory or its path ends in /, the source file or directory will not be placed inside it.
For example, to copy /a/b/c into /d/e/ and keep the name c, specify /d/e/c as the destination, not just /d/e/.
If the destination already exists, the mode parameter determines what happens: the default mode fails, overwrite mode replaces the destination itself, and directory merge modes merge the source directory contents into the destination directory.
Keywords: copy file, duplicate file, copy directory, duplicate directory, copy folder, duplicate folder.
This function is available only in versions released after 20250313.

Example​

ok, err = file.copy(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('Copy failed: '..err)
end

Note: The code above uses sys.alert, a function outside this chapter.

Copy to another directory and keep the name​

-- Assume /d/e is an existing directory and /d/e/c does not yet exist
file.copy('/a/b/c', '/d/e/c') -- Correct: copy c as /d/e/c

-- Incorrect: the target is e itself, not c inside e
file.copy('/a/b/c', '/d/e/') -- Default mode fails because the destination already exists

-- Overwrite mode replaces e itself; it does not create /d/e/c (20250914+)
-- file.copy('/a/b/c', '/d/e/', 'overwrite')

Wrap a “copy into directory” function​

The following custom wrapper requires a version released after 20250914. The destination directory must already exist. The function keeps the source file or directory name and passes the optional mode parameter to file.copy. Conflicts with an existing name are still handled according to the specified mode.

local function file_copy_into(src_path, dst_dir, mode)
if file.exists(dst_dir) ~= "directory" then
return false, "Target is not a directory"
end

local name, err = file.path.last_component(src_path)
if not name then
return false, err
end
-- Avoid using the destination directory itself or its parent as the final target.
if name == "" or name == "/" or name == "." or name == ".." then
return false, "Source path must end with a file or directory name"
end

local dst_path, path_err = file.path.add_component(dst_dir, name)
if not dst_path then
return false, path_err
end
return file.copy(src_path, dst_path, mode)
end

-- Assume /d/e is an existing directory; copy c as /d/e/c
local ok, err = file_copy_into("/a/b/c", "/d/e/")
if not ok then
print("Copy failed: "..err)
end

-- To replace /d/e/c, specify overwrite mode when calling the function:
-- file_copy_into("/a/b/c", "/d/e/", "overwrite")

Note: The code above uses file.exists, file.path.last_component, and file.path.add_component.